package ca.swank.hardquor;

/**
* Provides an interface for creating Hardquor players. To develop
* a hardquor player:
* <OL>
*   <LI>create a player class which implements this interface.
*   <LI>construct a <CODE>hardquorClient</CODE> object with this as the argument.
*   <LI>communication occurs between the <CODE>hardquorClient</CODE> and the player.
*   <LI>provide user interface or other logic for calling the methods of <CODE>hardquorClient</CODE>.
*   <LI>when a game request has been accepted, the <CODE>startGame</CODE> method will
*       be called. Construct a game which implements hardquorUserGame using the argument
*       as a parameter to the constructor, and return this object.
*   <LI>ensure to disconnect any connections made to <CODE>hardquorClient</CODE> before exitting.
* </OL>
*
* @author Jesse Wilson
* @version 1.0 9/23/2001
*/
public interface hardquorUser
{

  /**
  * called upon connection to a hardquor game server. Upon having this method
  * called, the class implementation should call the <CODE>tryUsername</CODE>
  * method of the <CODE>hardquorClient</CODE>.
  *
  * @param reason a String reason why the username is being requested. This
  *        string will describe a request for a new username when a connection is
  *        created, or for an alternate username when a new username fails.
  */
  public void notifyRequestUserName(String reason);

  /**
  * provides a list of online users upon connection to a hardquor game.
  *
  * @param users an array of usernames, each corresponding to another user
  *        connected to the current hardquor game server.
  */
  public void notifyUserList(String[] users);

  /**
  * notification that another user has disconnected from the hardquor game
  * server. The offline user is now no longer to accept game requests, and
  * game requests from this player are now void.
  *
  * @param username the user who has disconnected from the current hardquor game
  *        server.
  */
  public void notifyUserGone(String username);

  /**
  * notification that another user has connected to the current hardquor game
  * server. Game requests can be made to this player, and such may come from
  * the player.
  *
  * @param username the user who has connected to the current hardquor game
  *        server.
  */
  public void notifyUserNew(String username);

  /**
  * a chat message received from the specified user. Chat messages should
  * be displayed to the game player in order for players to carry out a
  * conversation. Chat messages from the current user will also be notified
  * via this method. Note that chat messages received by this class are
  * out of game messages, and distinct from in game messages.
  *
  * @param user the username who created the message
  * @param message the text of the message
  */
  public void notifySpeak(String user, String message);

  /**
  * an incoming game request from another user on the current hardquor server.
  * Upon having this method called, the request can be accepted by calling the
  * method <CODE>acceptGameRequest</CODE> of <CODE>hardquorClient</CODE> with
  * the same <CODE>hardquorGameRequest</CODE> object as the argument. To decline
  * a request, no action needs to be taken. Multiple game requests may be made,
  * and multiple requests can be accepted. Upon accepting a request, the
  * <CODE>startGame</CODE> method will be called, providing the request is still
  * active.
  *
  * @param request details regarding the proposed game. This includes the name
  *        of the requesting opponent, and which player number the request has
  *        the current player playing (ie. go first or go second).
  */
  public void notifyGameRequest(hardquorGameRequest request);


  /**
  * requests the user create an instance of an implementation of the
  * <CODE>hardquorUserGame</CODE>. HardquorUserGame implementations should
  * require a <CODE>hardquorGameClient</CODE> instance as a parameter for
  * construction; this provides communication between the user game and the
  * game server. The constructed <CODE>hardquorUserGame</CODE> implementation
  * shall be returned.
  *
  * @param gameClient an instance of the gameClient class to provide communication
  *        between the game and the current hardquor game server. It is important
  *        to provide the constructed object with this instance, as it is tied
  *        tightly to the <CODE>hardquorClient</CODE> for this user.
  * @param playerNumber the player that this gameClient will supply the moves
  *        for.
  * @return a constructed hardquorUserGame implemenation. This implementation
  *        should be constructed with the provided gameClient as an argument.
  */
  public hardquorUserGame startGame(hardquorGameClient gameClient, int playerNumber);

}